package module.StoreService;

import common.model.Entity.StoreEntity.Cart;
import network.protocol.Response;
import java.util.Optional;

/**
 * {@code CartService} 定义了购物车的核心业务操作接口。
 * <p>
 * 提供与购物车相关的功能，包括：
 * <ul>
 *     <li>根据用户 ID 获取购物车</li>
 *     <li>为用户创建购物车</li>
 *     <li>清空购物车内容</li>
 *     <li>根据用户 ID 获取或创建购物车 ID</li>
 * </ul>
 * <p>
 * 所有方法返回统一封装的 {@link Response} 对象，
 * 以便调用方能统一处理业务成功或失败的结果。
 */
public interface CartService {

    /**
     * 根据用户 ID 获取该用户的购物车。
     *
     * @param userId 用户的唯一标识
     * @return 包含购物车对象的响应；
     *         如果用户尚未创建购物车，则返回 {@link Optional#empty()}
     */
    Response<Optional<Cart>> getCartByUserId(long userId);

    /**
     * 为指定用户创建一个新的购物车。
     * <p>
     * 如果该用户已存在购物车，可能返回失败或忽略重复创建。
     *
     * @param userId 用户的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> createCart(long userId);

    /**
     * 清空指定用户的购物车内容。
     * <p>
     * 该操作不会删除购物车本身，只会移除其中的购物车项。
     *
     * @param userId 用户的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> clearCart(long userId);

    /**
     * 根据用户 ID 获取购物车 ID。
     * <p>
     * 如果该用户没有购物车，则会创建一个新的购物车并返回其 ID。
     *
     * @param userId 用户的唯一标识
     * @return 包含购物车 ID 的响应对象
     */
    Response<Long> getOrCreateCartId(long userId);
}
